Title

Add Matomo analytics integration for GitBook (pageviews, referrers, clicks, goals, SPA)

Overview

Adds a new analytics integration enabling published GitBook sites to send analytics to a Matomo cloud or self‑hosted instance. Consent-aware and SPA-friendly.

• Folder: integrations/matomo
• Target: site
• Consent: respects GitBook cookie consent
• SPA: tracks client-side navigations

Implementation

• integrations/matomo/gitbook-manifest.yaml
  • Scopes: site:script:inject, site:script:cookies
  • Category: analytics
  • CSP: allows script-src, img-src, connect-src to user-provided Matomo hosts (host is configured per site)
  • Configurations:
    • server_url (required): Matomo base URL
    • site_id (required): Matomo site ID
    • load_js_tracker (default true): load matomo.js for richer tracking; beacon fallback when disabled
    • track_referrer (default true)
    • track_outbound_clicks (default true)
    • click_selectors (string): comma-separated CSS selectors for custom click events
    • goal_mappings_json (string): JSON mapping of CSS selectors → Matomo Goal IDs
    • user_id_cookie (string): cookie name to set Matomo uid
• integrations/matomo/src/index.ts: serves configured tracking script
• integrations/matomo/src/matomoScript.raw.js:
  • Pageviews (initial + SPA)
  • Optional matomo.js load (first‑party cookies, enableLinkTracking)
  • Referrer (configurable)
  • Outbound link tracking (configurable)
  • Custom click tracking via selectors
  • Goal triggers from selector mappings
  • Optional uid from cookie
• Supporting files: global.d.ts, package.json, tsconfig.json, CHANGELOG.md, assets/icon.png

Security and privacy

• Honors GitBook consent (no tracking before consent)
• Uses first‑party matomo.js when enabled; otherwise a lightweight Tracking API beacon to the configured host
• CSP is permissive to support user‑defined Matomo hosts (can be narrowed if host-level CSP becomes dynamic)

Testing

• Install CLI and run a dev session for a space:
  • npm i -g @gitbook/cli
  • gitbook auth --token <token>
  • From integrations/matomo: gitbook dev <spaceId>
• Configure in the space: server_url, site_id (+ optional fields)
• Validate requests to <server_url>/matomo.php and, if enabled, <server_url>/matomo.js
• Confirm pageviews (initial + SPA), optional referrers, outbound clicks, configured selector events, and goals

References

• Matomo: Integrate Matomo (developer.matomo.org/integration)
• GitBook: Integrations overview (link), CLI (link), Configurations (link), Runtime (link)